使用 Python FastAPI 和 OpenAPI 规范精通 API 文档

            pip install fastapi "uvicorn[standard]"
            

              
                Copy
              
            
          

            from fastapi import FastAPI
from typing import Optional
from pydantic import BaseModel

app = FastAPI(
    title="Global Item Management API",
    description="A simple API to manage items for diverse international users.",
    version="1.0.0",
    contact={
        "name": "API Support Team",
        "url": "https://example.com/contact",
        "email": "support@example.com",
    },
    license_info={
        "name": "MIT License",
        "url": "https://opensource.org/licenses/MIT",
    },
)

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

@app.get("/")
async def read_root():
    """
    Provides a welcome message for the API.
    """
    return {"message": "Welcome to the Global Item Management API!"}

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int, q: Optional[str] = None):
    """
    Retrieve details for a specific item by its unique ID.

    - <b>item_id</b>: The ID of the item to retrieve.
    - <b>q</b>: An optional query string for filtering or searching.
    """
    item_data = {"name": "Example Item", "price": 12.5}
    if q:
        item_data["description"] = f"A wonderful {item_data['name']} related to '{q}'."
    else:
        item_data["description"] = "A standard item available globally."
    return item_data

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    Create a new item in the system.

    This endpoint accepts an Item object in the request body
    and returns the created item's details.
    """
    # In a real application, you'd save this to a database
    print(f"Received item: {item.dict()}")
    return item

            

              
                Copy
              
            
          

            uvicorn main:app --reload
            

              
                Copy
              
            
          

            from fastapi import FastAPI

app = FastAPI(
    title="Global Financial Services API",
    description="This API provides real-time financial data and transaction processing for international clients.",
    version="2.1.0",
    terms_of_service="https://example.com/terms/",
    contact={
        "name": "Global API Support",
        "url": "https://example.com/contact/",
        "email": "api-support@example.com",
    },
    license_info={
        "name": "Proprietary License",
        "url": "https://example.com/license/",
    },
    # You can also specify the openapi_url if you want to change the default /openapi.json
    # openapi_url="/v2/openapi.json"
)

@app.get("/status")
async def get_status():
    """Checks the operational status of the API."""
    return {"status": "Operational", "uptime": "99.9%"}

            

              
                Copy
              
            
          

            from fastapi import FastAPI, Path, Query
from typing import Optional

app = FastAPI()

@app.get(
    "/products/{product_id}",
    summary="Retrieve details of a specific product",
    description="This endpoint fetches comprehensive information about a product, including its name, price, and availability across different regions. Use a numeric product_id.",
)
async def get_product(
    product_id: int = Path(..., description="The unique identifier of the product to retrieve", ge=1),
    region: Optional[str] = Query(
        None,
        description="Optional: Filter product availability by region (e.g., 'EMEA', 'APAC', 'AMERICAS').",
        example="EMEA"
    )
):
    """
    Fetches product details from the database.
    If a region is provided, it can filter regional data.
    """
    # ... logic to fetch product ...
    return {"product_id": product_id, "name": "Global Gadget", "price": 99.99, "region": region}

            

              
                Copy
              
            
          

            from fastapi import FastAPI, Depends, HTTPException, status
from typing import List, Dict

# Define tags with metadata for better organization
tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. Manage user profiles and authentication.",
    },
    {
        "name": "items",
        "description": "Manage items in the inventory. CRUD operations for products.",
    },
    {
        "name": "admin",
        "description": "<b>Admin-level operations</b> requiring elevated privileges. Handle system configurations.",
        "externalDocs": {
            "description": "Admin documentation",
            "url": "https://example.com/admin_docs",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)

async def get_current_user():
    # Placeholder for a real authentication dependency
    return {"username": "admin_user", "roles": ["admin"]}

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "Alice"}, {"username": "Bob"}]

@app.post("/items/", tags=["items"])
async def create_item():
    return {"message": "Item created"}

@app.delete("/admin/clear-cache", tags=["admin"])
async def clear_cache(current_user: Dict = Depends(get_current_user)):
    if "admin" not in current_user["roles"]:
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
    return {"message": "Cache cleared by admin"}

            

              
                Copy
              
            
          

            from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime

app = FastAPI()

class Location(BaseModel):
    city: str = Field(..., description="The city name of the location.")
    country: str = Field(..., description="The country name, e.g., 'Germany', 'Japan', 'Brazil'.")
    latitude: float = Field(..., description="Geographical latitude.", ge=-90, le=90)
    longitude: float = Field(..., description="Geographical longitude.", ge=-180, le=180)

class SensorData(BaseModel):
    sensor_id: str = Field(..., example="sensor-001-eu", description="Unique identifier for the sensor. Must be non-empty.")
    timestamp: datetime = Field(..., description="Timestamp of the data reading in ISO 8601 format.")
    temperature_celsius: float = Field(..., description="Temperature reading in Celsius.", ge=-273.15)
    humidity_percent: Optional[float] = Field(None, description="Relative humidity in percent.", ge=0, le=100)
    location: Location = Field(..., description="Geographical location where the sensor data was recorded.")

@app.post("/sensors/data", response_model=SensorData, summary="Submit new sensor data")
async def receive_sensor_data(data: SensorData):
    """
    Accepts sensor data from various global monitoring stations.

    The data includes a unique sensor ID, timestamp, temperature,
    optional humidity, and location details.
    """
    print(f"Received sensor data: {data.json()}")
    # In a real application, this data would be stored or processed
    return data

@app.get("/sensors/latest/{sensor_id}", response_model=SensorData, summary="Get latest data for a sensor")
async def get_latest_sensor_data(
    sensor_id: str = Path(..., description="The ID of the sensor to retrieve data for.", min_length=5)
):
    """
    Retrieves the most recent data point for a specified sensor.
    """
    # Simulate fetching latest data
    mock_data = SensorData(
        sensor_id=sensor_id,
        timestamp=datetime.now(),
        temperature_celsius=25.5,
        humidity_percent=60.0,
        location=Location(city="Tokyo", country="Japan", latitude=35.6895, longitude=139.6917)
    )
    return mock_data

            

              
                Copy
              
            
          

            from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field
from typing import Dict

app = FastAPI()

class ErrorDetail(BaseModel):
    message: str = Field(..., description="A human-readable message explaining the error.")
    code: str = Field(..., description="An internal error code for programmatic identification.")

class User(BaseModel):
    user_id: str = Field(..., example="user-gb-123", description="Unique identifier for the user.")
    name: str
    email: str

# Simulate a user database
fake_users_db = {
    "user-gb-123": {"name": "John Doe", "email": "john.doe@example.com"},
    "user-fr-456": {"name": "Jeanne Dupont", "email": "jeanne.dupont@example.com"},
}

@app.get(
    "/users/{user_id}",
    response_model=User,
    responses={
        status.HTTP_404_NOT_FOUND: {
            "model": ErrorDetail,
            "description": "The user was not found.",
            "content": {
                "application/json": {
                    "example": {"message": "User with ID 'user-gb-999' not found.", "code": "USER_NOT_FOUND"}
                }
            }
        },
        status.HTTP_400_BAD_REQUEST: {
            "model": ErrorDetail,
            "description": "Invalid user ID format.",
            "content": {
                "application/json": {
                    "example": {"message": "Invalid user ID format. Must start with 'user-'.", "code": "INVALID_ID_FORMAT"}
                }
            }
        },
        status.HTTP_500_INTERNAL_SERVER_ERROR: {
            "model": ErrorDetail,
            "description": "Internal server error.",
            "content": {
                "application/json": {
                    "example": {"message": "An unexpected error occurred.", "code": "INTERNAL_SERVER_ERROR"}
                }
            }
        }
    },
    summary="Get user details by ID"
)
async def get_user(user_id: str):
    """
    Retrieves detailed information for a specific user.

    Raises:
        HTTPException 400: If the user ID format is invalid.
        HTTPException 404: If the user is not found.
    """
    if not user_id.startswith("user-"):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail={"message": "Invalid user ID format. Must start with 'user-'.", "code": "INVALID_ID_FORMAT"}
        )

    user_data = fake_users_db.get(user_id)
    if not user_data:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail={"message": f"User with ID '{user_id}' not found.", "code": "USER_NOT_FOUND"}
        )
    return User(user_id=user_id, **user_data)

            

              
                Copy
              
            
          

            from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from pydantic import BaseModel, Field
from typing import Dict

# Define OAuth2 bearer scheme
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

# Placeholder for user management (in a real app, this would be from a database)
class UserInDB(BaseModel):
    username: str
    hashed_password: str
    full_name: Optional[str] = None
    email: Optional[str] = None
    disabled: Optional[bool] = None

def get_user_from_db(username: str):
    # Simulate a database lookup
    users_db = {
        "admin@example.com": UserInDB(
            username="admin@example.com",
            hashed_password="fakehashedpassword", # In real app, hash this!
            full_name="Admin User",
            email="admin@example.com"
        )
    }
    return users_db.get(username)

async def get_current_user(token: str = Depends(oauth2_scheme)):
    # In a real app, you'd decode the JWT token, validate it, and fetch the user
    # For this example, we'll just check if it's a known token or return a dummy user
    if token == "secure-token-123":
        return get_user_from_db("admin@example.com")
    raise HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Invalid authentication credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )

app = FastAPI(
    title="Secure Global API",
    description="An API demonstrating OAuth2 authentication for sensitive endpoints.",
    version="1.0.0"
)

@app.get("/items/secure/", tags=["items"], summary="Retrieve all secure items (requires authentication)")
async def read_secure_items(current_user: UserInDB = Depends(get_current_user)):
    """
    Fetches a list of items that are only accessible to authenticated users.
    """
    return [
        {"item_id": "secure-item-001", "owner": current_user.username},
        {"item_id": "secure-item-002", "owner": current_user.username}
    ]

@app.post("/token", tags=["authentication"], summary="Obtain an OAuth2 token")
async def login_for_access_token(
    username: str = Field(..., description="User's email for login"),
    password: str = Field(..., description="User's password")
):
    # In a real app, validate username/password against stored credentials
    if username == "admin@example.com" and password == "secret":
        # In a real app, generate a JWT token
        return {"access_token": "secure-token-123", "token_type": "bearer"}
    raise HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Incorrect username or password",
        headers={"WWW-Authenticate": "Bearer"},
    )

            

              
                Copy
              
            
          

            app = FastAPI(
    title="Customized Docs API",
    swagger_ui_parameters={"docExpansion": "list", "filter": True}
)

            

              
                Copy